Developer Documentation

QuickTime 4 API Documentation

Inside Macintosh: QuickTime

Previous | Overview | Contents | Next |

Working With Time Base Values

Every time base contains a rate, a start time, a stop time, a current time, and some status information. The Movie Toolbox provides a number of functions that allow your application to work with the contents of a time base. This section describes those functions.

The GetTimeBaseTime function lets you retrieve the current time value of a time base. You can set the current time value by calling the SetTimeBaseTime function--this function requires you to provide a time structure. Alternatively, you can set the current time based on a time value by calling the SetTimeBaseValue function.

You can determine the rate of a time base by calling the GetTimeBaseRate function. You can set the rate of a time base by calling the SetTimeBaseRate function. You can determine the effective rate of a specified time base (relative to the master time base to which it is subordinate) by calling the GetTimeBaseEffectiveRate function.

You can retrieve the start time of a time base by calling the GetTimeBaseStartTime function. You can set the start time of a time base by calling the SetTimeBaseStartTime function. Similarly, you can use the GetTimeBaseStopTime and SetTimeBaseStopTime functions to work with the stop time of a time base.

The Movie Toolbox provides functions that allow you to work with the status information of a time base. The GetTimeBaseStatus function allows you to read the current status of a time base. The GetTimeBaseFlags function helps you obtain the control flags of a time base. You can set these flags by calling the SetTimeBaseFlags function.

SetTimeBaseTime

The SetTimeBaseTime function allows your application to set the current time of a time base. You must specify the new time in a time structure.

pascal void SetTimeBaseTime (TimeBase tb, const TimeRecord *tr);
tb
Specifies the time base for this operation. Your application obtains this time base identifier from the NewTimeBase function (described on NewTimeBase ).

tr
Contains a pointer to a time structure that contains the current time value.

DESCRIPTION

If you set the current time of a time base that is the master time base for other time bases, the current times in all the dependent time bases are changed appropriately. If you change the current time in a time base that relies on a master time base, the Movie Toolbox changes the offset between the time base and the master time base--the master time base is not affected.

ERROR CODES

None

SEE ALSO

You can set the current time of a time base from a time value by calling the SetTimeBaseValue function, which is described in the next section.

SetTimeBaseValue

The SetTimeBaseValue function allows your application to set the current time of a time base. You must specify the new time as a time value.

pascal void SetTimeBaseValue (TimeBase tb, TimeValue t,
                                          TimeScale s);
tb
Specifies the time base for this operation. Your application obtains this time base identifier from the NewTimeBase function (described on NewTimeBase ).

t
Specifies the new time value.

s
Specifies the time scale of the new time value.

DESCRIPTION

If you set the current time of a time base that is the master time base for other time bases, the current times in all the dependent time bases are changed appropriately. If you change the current time in a time base that relies on a master time base, the Movie Toolbox changes the offset between the time base and the master time base--the master time base is not affected.

ERROR CODES

None

SEE ALSO

You can set the current time of a time base from a time structure by calling the SetTimeBaseTime function, which is described in the previous section.

GetTimeBaseTime

Your application can use the GetTimeBaseTime function to obtain the current time value from a time base. You can specify the time scale in which to return the time value.

pascal TimeValue GetTimeBaseTime (TimeBase tb, TimeScale s,
                                          TimeRecord *tr);
tb
Specifies the time base for this operation. Your application obtains this time base identifier from the NewTimeBase function (described on NewTimeBase ).

s
Specifies the time scale in which to return the current time value. Set this parameter to 0 to retrieve the time in the preferred time scale of the time base.

tr
Contains a pointer to a time structure that is to receive the current time value. This is an optional parameter. If you do not want the time value represented in a time structure, set this parameter to nil .

DESCRIPTION

The GetTimeBaseTime function returns a time value that contains the current time from the specified time base in the specified time scale. The function returns this value even if you specify a time structure with the tr parameter.

ERROR CODES

None

SEE ALSO

You can set the current time of a time base by calling either the SetTimeBaseTime or SetTimeBaseValue functions, which are described on SetTimeBaseTime and SetTimeBaseValue , respectively.

SetTimeBaseRate

The SetTimeBaseRate function allows your application to set the rate of a time base.

pascal void SetTimeBaseRate (TimeBase tb, Fixed r);
tb
Specifies the time base for this operation. Your application obtains this time base identifier from the NewTimeBase function (described on NewTimeBase ).

r
Specifies the rate of the time base.

DESCRIPTION

You can determine the number of time units that pass each second for a time base by multiplying its rate by the time scale of its time coordinate system. For example, if you set the rate of a time base to 2 and the time base has a time scale of 2, that time base passes through 4 units of its time each second.

Rates may be set to negative values. Negative rates cause time to move backward for the time base.

ERROR CODES

None

SEE ALSO

You can retrieve the rate of a time base by calling the GetTimeBaseRate function, which is described in the next section.

GetTimeBaseRate

The GetTimeBaseRate function allows your application to retrieve the rate of a time base.

Rates may be set to negative values. Negative rates cause time to move backward for the time base.

pascal Fixed GetTimeBaseRate (TimeBase tb);
tb
Specifies the time base for this operation. Your application obtains this time base identifier from the NewTimeBase function (described on NewTimeBase ).

DESCRIPTION

The GetTimeBaseRate function returns the current rate of the time base as a fixed-point number. This rate value may be nonzero even if the time base has stopped, because it has reached its stop time.

ERROR CODES

None

GetTimeBaseEffectiveRate

The GetTimeBaseEffectiveRate function returns the effective rate at which the specified time base is moving, relative to its master clock.

pascal Fixed GetTimeBaseEffectiveRate (TimeBase tb);
tb
Specifies the time base for this operation. Your application obtains this time base identifier from the NewTimeBase function (described on NewTimeBase ).

DESCRIPTION

The GetTimeBaseEffectiveRate function is useful when you need to make scheduling decisions based on the rate of a time base--for example, when you are writing a media handler. (For more on media handlers, see Inside Macintosh: QuickTime Components.) By calling GetTimeBaseEffectiveRate rather than the GetTimeBaseRate function (described in the previous section), you can easily take into account any time base subordination that may be in effect.

SetTimeBaseStartTime

You can set the start time of a time base by calling the SetTimeBaseStartTime function. The start time defines the time base's minimum time value. You must specify the new start time in a time structure.

pascal void SetTimeBaseStartTime (TimeBase tb,
                                         const TimeRecord *tr);
tb
Specifies the time base for this operation. Your application obtains this time base identifier from the NewTimeBase function (described on NewTimeBase ).

tr
Contains a pointer to a time structure that contains the start time value.

DESCRIPTION

Do not use this function to restrict the Movie Toolbox to a portion of a movie--use the SetMovieActiveSegment function (described on SetMovieActiveSegment ) instead.

ERROR CODES

None

SEE ALSO

You can determine the start time of a time base by calling the GetTimeBaseStartTime function, which is described in the next section.

GetTimeBaseStartTime

You can determine the start time of a time base by calling the GetTimeBaseStartTime function.

pascal TimeValue GetTimeBaseStartTime (TimeBase tb, TimeScale s,
                                          TimeRecord *tr);
tb
Specifies the time base for this operation. Your application obtains this time base identifier from the NewTimeBase function (described on NewTimeBase ).

s
Specifies the time scale in which to return the start time.

tr
Contains a pointer to a time structure that is to receive the start time. This is an optional parameter. If you do not want the time value represented in a time structure, set this parameter to nil .

DESCRIPTION

The GetTimeBaseStartTime returns a time value that contains the start time from the specified time base in the specified time scale. The function returns this value even if you specify a time structure with the tr parameter.

ERROR CODES

None

SEE ALSO

You can set the start time of a time base by calling the SetTimeBaseStartTime function, which is described in the previous section.

SetTimeBaseStopTime

You can set the stop time of a time base by calling the SetTimeBaseStopTime function. The stop time defines the time base's maximum time value. You must specify the new stop time in a time structure.

pascal void SetTimeBaseStopTime (TimeBase tb,
                                         const TimeRecord *tr);
tb
Specifies the time base for this operation. Your application obtains this time base identifier from the NewTimeBase function (described on NewTimeBase ).

tr
Contains a pointer to a time structure that contains the stop time value.

DESCRIPTION

Do not use the SetTimeBaseStopTime function to restrict the Movie Toolbox to a portion of a movie--use the SetMovieActiveSegment function (described on SetMovieActiveSegment ) instead.

ERROR CODES

None

SEE ALSO

You can determine the stop time of a time base by calling the GetTimeBaseStopTime function, which is described in the next section.

GetTimeBaseStopTime

You can determine the stop time of a time base by calling the GetTimeBaseStopTime function.

pascal TimeValue GetTimeBaseStopTime (TimeBase tb, TimeScale s,
                                          TimeRecord *tr);
tb
Specifies the time base for this operation. Your application obtains this time base identifier from the NewTimeBase function (described on NewTimeBase ).

s
Specifies the time scale in which to return the stop time.

tr
Contains a pointer to a time structure that is to receive the stop time. This is an optional parameter. If you do not want the time value represented in a time structure, set this parameter to nil .

DESCRIPTION

The GetTimeBaseStopTime returns a time value that contains the stop time from the specified time base in the specified time scale. The function returns this value even if you specify a time structure with the out parameter.

ERROR CODES

None

SEE ALSO

You can set the stop time of a time base by calling the SetTimeBaseStopTime function, which is described in the previous section.

SetTimeBaseFlags

The SetTimeBaseFlags function allows your application to set the contents of the control flags of a time base.

pascal void SetTimeBaseFlags (TimeBase tb, long timeBaseFlags);
tb
Specifies the time base for this operation. Your application obtains this time base identifier from the NewTimeBase function (described on NewTimeBase ).

timeBaseFlags
Specifies the control flags for this time base. The following flags are defined. You may set only one flag to 1 (be sure to set unused flags to 0):

loopTimeBase
Indicates whether the time base loops. If you set this flag to 1 and the rate is positive, the time base loo ps back and restarts from its start time when it reaches its stop time. If you set this flag to 1 and the rate is negative, the time base loops to its stop time. If you set the flag to 0, the movie stops when it reaches the end.

palindromeLoopTimeBase
Indicates whether the time base loops in a palindrome fashion. Palindrome looping causes a time base to move alternately forward and backward. Set this flag to 1 to cause the time base to loop in this manner.

ERROR CODES

None

SEE ALSO

You can retrieve the control flags of a time base by calling the GetTimeBaseFlags function, which is described in the next section.

GetTimeBaseFlags

The GetTimeBaseFlags function allows your application to obtain the contents of the control flags of a time base.

pascal long GetTimeBaseFlags (TimeBase tb);
tb
Specifies the time base for this operation. Your application obtains this time base identifier from the NewTimeBase function (described on NewTimeBase ).

DESCRIPTION

The GetTimeBaseFlags function returns the control flags of a time base. The following flags are defined (unused flags are set to 0):

loopTimeBase
Indicates whether the time base loops. If this flag is set to 1 and the rate is positive, the time base loops back and restarts from its start time when it reaches its stop time. If this flag is set to 1 and the rate is negative, the time base loops to its stop time. If the flag is set to 0, the movie stops when it reaches the end.

palindromeLoopTimeBase
Indicates whether the time base loops in a palindrome fashion. Palindrome looping causes a time base to move alternately forward and backward. If this flag is set to 1, the time base is palindrome looping.

ERROR CODES

None

SEE ALSO

You can set the control flags of a time base by calling the SetTimeBaseFlags function, which is described in the previous section.

GetTimeBaseStatus

Your application can retrieve status information from a time base by calling the GetTimeBaseStatus function. This status information allows you to determine when the current time of a time base would fall outside of the range of values specified by the start and stop times of the time base. This can happen when a time base relies on a master time base or when its time has reached the stop time.

pascal long GetTimeBaseStatus (TimeBase tb,
                                         TimeRecord *unpinnedTime);
tb
Specifies the time base for this operation. Your application obtains this time base identifier from the NewTimeBase function (described on NewTimeBase ).

unpinnedTime
Contains a pointer to a time structure that is to receive the current time of the time base. Note that this time value may be outside the range of values specified by the start and stop times of the time base.

DESCRIPTION

The GetTimeBaseStatus function returns flags that indicate whether the returned time value is outside the range of values specified by the start and stop times of the time base. The following flags are defined (unused flags are set to 0):

timeBaseBeforeStartTime
Indicates that the time value represented by the contents of the time structure referred to by the unpinnedTime parameter lies before the start time of the time base. The Movie Toolbox sets this flag to 1 if the current time is before the start time of the time base.

timeBaseAfterStopTime
Indicates that the time value represented by the contents of the time structure referred to by the unpinnedTime parameter lies after the stop time of the time base. The Movie Toolbox sets this flag to 1 if the current time is after the stop time of the time base.

ERROR CODES

None

© 1999 Apple Computer, Inc.

Previous | Overview | Contents | Next